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SYNOPSIS 


package require Tcl 8.5 9 

package require fileutil::multi ?0.2? 
package require fileutil::multi::op ?0.5.4? 
package require wip ?1.1? 


ifileutil::multi ?word...? 


DESCRIPTION 


This package provides a single command to perform actions on multiple files selected by glob patterns. It is a thin layer over the 
package fileutil::multi::op which provides objects for the same. This package simply creates a single such object and directs all 
file commands to it. 


At the core is a domain specific language allowing the easy specification of multi-file copy and/or move and/or deletion 
operations. Alternate names would be scatter/gather processor, or maybe even assembler. For the detailed specification of this 
language, and examples, please see the documention for the package fileutil::multi::op. 


PUBLIC API 


The main command of the package is: 


e ::fileutil::multi ?word...? 


This command interprets the specified words as file commands to execute. See the section FILE API of the documentation 
for the package fileutil::multi::op for the set of acceptable commands, their syntax, and semantics. 


The result of the command is the result generated by the last file command it executed. 
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SYNOPSIS 


package require Tcl 8.5 9 
package require fileutil::multi::op ?0.5.4? 
package require wip ?1.0? 


::fileutil::multi::op ?0pName? ?word...? 
opName option ?arg arg...? 
SopName do ?word...? 

into directory 

in directory 

to directory 

from directory 

not pattern 

for pattern 

exclude pattern 

but 

except 

as name 

recursive 


recursively 
copy 

move 

remove 

expand 

invoke cmdprefix 


cd directory 
up 
for-windows 
for-win 
for-unix 
the pattern 
the-set varname 
-> varname 
strict 
'strict 

files 

links 
directories 
dirs 

all 

state? 

as? 
excluded? 
from? 
into? 
operation? 
recursive? 
strict? 
type? 


DESCRIPTION 


This package provides objects which are able to perform actions on multiple files selected by glob patterns. 


At the core is a domain specific language allowing the easy specification of multi-file copy and/or move and/or deletion 
operations. Alternate names would be scatter/gather processor, or maybe even assembler. 


CLASS API 


The main command of the package is: 
e ::fileutil::multi::op ?0pName? ?word...? 


The command creates a new multi-file operation object with an associated global Tcl command whose name is opName. 
This command can be used to invoke the various possible file operations. It has the following general form: 


°© opName option ?arg arg...? 
Option and the args determine the exact behavior of the command. 
If the string %AUTO% is used as the opName then the package will generate a unique name on its own. 


If one or more words are specified they are interpreted as an initial set of file commands to execute. I.e. the method do of 
the newly constructed object is implicitly invoked using the words as its arguments. 


OBJECT API 


The following methods are possible for multi-file operation objects: 
© $opName do ?word...? 


This method interprets the specified words as file commands to execute. See the section FILE API for the set of acceptable 
commands, their syntax, and semantics. 


The result of the method is the result generated by the last file command it executed. 


FILE API 


Both object constructor and method do take a list of words and interpret them as file commands to execute. The names were 
chosen to allow the construction of operations as sentences in near-natural language. Most of the commands influence just the 
state of the object, i.e. are simply providing the configuration used by the command triggering the actual action. 


into directory 

Specifies the destination directory for operations. 
in directory 

Alias for into. 

to directory 

Alias for into. 

from directory 

Specifies the source directory for operations. 

not pattern 

Specifies a glob pattern for paths to be excluded from the operation. 
for pattern 

Alias for not. 

exclude pattern 

Alias for not. 

but 


Has no arguments of its own, but looks ahead in the list of words and executes all not commands immediately following it. 
This allows the construction of "but not" and "but exclude" clauses for a more natural sounding specification of excluded 
paths. 


except 


A semi-alias for but. Has no arguments of its own, but looks ahead in the list of words and executes all for commands 
immediately following it. This allows the construction of "except for" clauses for a more natural sounding specification of 
excluded paths. 


as name 


Specifies a new name for the first file handled by the current operation. I.e. for the renaming of a single file during the 
operation. 


recursive 

Signals that file expansion should happen in the whole directory hierarchy and not just the directory itself. 
recursively 

An alias for recursive. 


copy 


Signals that the operation is the copying of files from source to destination directory per the specified inclusion and 
exclusion patterns. 


move 


Signals that the operation is the moving of files from source to destination directory per the specified inclusion and 


exclusion patterns. 
remove 


Signals that the operation is the removal of files in the destination directory per the specified inclusion and exclusion 
patterns. 


expand 


Signals that there is no operation but the calculation of the set of files from the include and exclude patterns. This 
operation is not available if the-set is used. 


invoke cmdprefix 


Signals that the user-specified command prefix cmdprefix is the operation to perform. The command prefix is executed at 
the global level and given the source directory, destination directory, and set of files (as dictionary mapping from source to 
destination files), in this order. 


reset 

Forces the object into the ground state where all parts of the configuration have default values. 
( 

Saves a copy of the current object state on a stack. 

) 

Takes the state at the top of the state stack and restores it, i.e. makes it the new current object state. 
cd directory 

Changes the destination directory to the sub-directory directory of the current destination. 

up 

Changes the destination directory to the parent directory of the current destination. 
for-windows 

Checks that Windows is the current platform. Aborts processing if not. 

for-win 

An alias for for-windows. 

for-unix 

Checks that Unix is the current platform. Aborts processing if not. 

the pattern 


This command specifies the files to operate on per a glob pattern, and is also the active element, i.e. the command which 
actually performs the specified operation. All the other commands only modified the object state to set the operation up, 
but di nothing else. 


To allow for a more natural sounding syntax this command also looks ahead in the list of words looks and executes several 
commands immediately following it before performing its own actions. These commands are as, but, exclude, except, 
from, and into (and aliases). That way these commands act like qualifiers, and still take effect as if they had been written 
before this command. 


After the operation has been performed the object state the exclude patterns and the alias name, if specified, are reset to 
their default values (i.e. empty), but nothing else. 


the-set varname 


Like the, however the set of files to use is not specified implicitly per a glob pattern, but contained and loaded from the 
specified variable. The operation expand is not available if this command is used. 


-> varname 


Saves the set of files from the last expansion into the specified variable. 
e strict 


Make file expansion and definition of destination directory (in and aliases) strict, i.e. report errors for missing directories, 
and empty expansion. 


© strict 
Complement of strict. A missing destination directory or empty expansion are not reported as errors. 
e files 
Limit the search to files. Default is to accept every type of path. 
e links 
Limit the search to symbolic links. Default is to accept every type of path. 
e directories 
Limit the search to directories. Default is to accept every type of path. 
e dirs 
An alias for directories. 
° all 
Accept all types of paths (default). 
e state? 
Returns the current state of the object as dictionary. The dictionary keys and their meanings are: 
° as 
Last setting made by as. 
° excluded 
List of currently known exclusion patterns. 
o from 
Current source directory, set by from. 
© into 
Current destination directory, set by into (and aliases). 
© operation 
Current operation to perform, set by copy, move, remove, expand, or invoke. 
© recursive 
Current recursion status. Set/unset by recursive and !recursive. 
© strict 
Current strictness. Set/unset by strict and !strict. 
° type 
Current path type limiter. Set by either files, directories, links, or all. 
e as? 
Returns the current alias name. 


e excluded? 


Returns the current set of exclusion patterns. 
e from? 

Returns the current source directory. 
e into? 

Returns the current destination directory. 
© operation? 

Returns the current operation to perform. 
e recursive? 

Returns the current recursion status. 
e strict? 

Returns the current strictness. 
e type? 


Returns the current path type limiter. 


EXAMPLES 


The following examples assume that the variable F contains a reference to a multi-file operation object. 


$F do copy \ 
the *.dll \ 
from c:/TDK/PrivateOpenSSL/bin \ 
to [installdir_of tls] 


$F do move \ 
thes = \ 
from /sources \ 
into /scratch \ 
but not *.html 


# Alternatively use ‘except for *.html'. 


$F do \ 
move \ 
the index \ 
from /sources \ 
into /scratch \ 
as pkgIndex.tcl 


$F do \ 
remove ee 
thectstxt? \ 
in /scratch 


Note that the fact that most commands just modify the object state allows us to use more off forms as specifications instead of 
just nearly-natural language sentences. For example the second example in this section can re-arranged into: 


$F do \ 
from /sources \ 
into /scratch \ 
but not *.html \ 
move \ 
theo <* 


and the result is not only still a valid specification, but even stays relatively readable. 


Further note that the information collected by the commands but, except, and as is automatically reset after the associated the 
was executed. However no other state is reset in that manner, allowing the user to avoid repetitions of unchanging information. 
For example the second and third examples of this section can be merged and rewritten into the equivalent: 


$F do \ 
move e. 


the * \ 


from /sources \ 

into /scratch \ 
but not *.html not index \ 
the index \ 


as pkgIndex.tcl 


Bugs, Ideas, Feedback 


This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the 
category fileutil of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or 
documentation. 


When proposing code changes, please provide unified diffs, i.e the output of diff -u. 


Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of 
the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. 
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